FishMarket 1.0/FishMarket v1.0.iso/fishies/476-500/disk_478/mp/mp.doc

Text File | 1992-05-06 | 16KB | 472 lines

MP:        A MIDI Playground
Author:        Daniel J. Barrett, [e-mail].
No Copyright:    100% Public Domain.
        Please share this program with others.

Requirements:    A Commodore Amiga.
Optional:    A MIDI Interface on your serial port.
        1 or more MIDI instruments.
        (Without MIDI, this program is not very useful, except
         perhaps as a source code example for serial port
         programming and parsing input.)

Legal stuff:    Use this program entirely at your own risk.  The author
        bears no responsibility for any damage or data loss you
        may incur through the use or misuse of this program.


GETTING QUICK HELP

    At the command line, type:

        1>  mp ?

TABLE OF CONTENTS

Line    Section
===========================================================================
 18    Getting quick help
 24    Table of contents
 46    What is MP?
 77    What is MP not?
 84    MP concepts
118    A first exercise
132    Formal usage instructions for MP
162    The input text language
237    Practicing with the text language
264    Using the file input/output options to make new windows
277    Using redirection
306    Translating binary data to/from text
318    Using an alternate MIDI interface
359    Problems you may have with MP
425    Notes about the source code
457    Notes about the program's internals (and limitations)


WHAT IS MP?

    Have you ever wanted to see what MIDI data your instrument is
transmitting?  Have you ever wanted to send your own MIDI data to your
MIDI instrument?  Then MP is for you!!

    MP (MIDI Playground) is a versatile tool for sending, receiving,
and storing MIDI data.  It has many uses:

    o    Learning about MIDI.

    o    Discovering your instrument's system exclusive data
        format.

    o    Testing your instrument's MIDI capabilities.

    o    Acting as a patch librarian.  (VERY VERY basic, though.)

    o    Helping you write MIDI software.

    Essentially, MP is a "translator" program that understands 3
data formats and translates between any pair:

        (1)    English text
        (2)    Binary data
        (3)    MIDI data

Formats (2) and (3) are really the same, but (2) is stored in files on your
Amiga, and (3) is transmitted via your MIDI interface.


WHAT IS MP NOT?

    MP is not a sequencer.  It does not store any kind of timing
information.  MP simply sends and receives bytes in the order they are
given.


MP CONCEPTS

    Like I said, MP translates between text, binary data, and MIDI
data.  All you need to do is:

    (1)    Choose a format for the input.
    (2)    Choose a format for the output.
        (The input and output formats can be the same if you like.)
    (3)    Run MP.

For example, you can ask MP to use "text" as input and "MIDI" as output.
This lets you type text in a very easy-to-learn language, and it immediately
gets sent out as MIDI data.  If you reverse these choices (input=MIDI,
output=text), you can watch MIDI data appear on your screen in a simple
but readable format.

    Another use would be to use "MIDI" as input and "binary" as output.
This lets you press keys and buttons on your instrument, and have all
the data stored in binary format in an Amiga file.  To send the data back
to the instrument, just use "binary" for input and "MIDI" for output!

    Yet another use is for MP to translate between binary data and
readable text.  This can help you to understand the contents of a binary
MIDI file, or to create binary MIDI files by typing simple text commands.
(Note:  this facility will work with ANY binary files, not just those
containing MIDI data.)

    You can also ask MP to translate from one format to the same
format!  For example, it can read MIDI data and "echo" it back to the
sending instrument (translating MIDI to MIDI), copy binary files (translating
binary to binary), or let you practice with its text language (text to
text).


A FIRST EXERCISE

    Let's ask MP to translate from MIDI into text.  Make sure your
MIDI synthesizer is hooked up properly to your Amiga.  Type:

        1>  mp  -im  -ot

(This asks MP to use MIDI input (-im) and text output (-ot).)

    Now go to your instrument and play notes, press buttons, turn
dials, etc.  You should see things appearing on your Amiga screen!  To
exit the program, type ^C (control-C) on the Amiga.


FORMAL USAGE INSTRUCTIONS FOR MP

    MP's syntax is:

        1>  mp  -i{tbm}  -o{tbm}  [-g infile]  [-p outfile]

The flags "-i" and "-o" are mandatory (they MUST appear, in any order).
The flag "-i" represents input, and "-o" represents output.  You also
must fill in the "[choice]" specifying text, binary, or MIDI.  The syntax
is:

        t    Text
        b    Binary data
        m    MIDI

For example, to read text from the keyboard and send to MIDI:

        1>  mp -it -om

To read MIDI data and convert it to text:

        1>  mp -ot -im

If you would like to GET your input from a file (not the keyboard), you may
specify a file name with the -g option.  Similarly, the -p option allows
you to PUT the output into a file (rather than the screen).  The -g and -p
options have no meaning, obviously, if your input and output are MIDI,
respectively.


THE INPUT TEXT LANGUAGE

    If you do not already know what MIDI code looks like (for
example, hexadecimal 90 means "Note On, MIDI channel 0"), then this
section might not be useful to you yet.  But feel free to try!

    MP understands many different kinds of text input.  To use the
text input feature, you must learn a very simple syntax.  If you are a
C programmer, you will recognize some of this language and feel right
at home.  (Don't worry... you don't have to be a C programmer to use MP!
It will take a little practice, though.)

    MP understands NUMBERS (between 0 and 255) in:

    -    Base 10 (decimal or "normal" numbers)
        Just type the number normally.
        Example:    123

    -    Base 8 (octal)
        Precede the number with a zero.
        Example:    024

    -    Base 16 (hexadecimal)
        Precede the number with an "H" or the symbol "0x".
        If the number begins with A through F, you can skip the
         above symbols.
        Examples:    0x2A     H44    F7

    -    Base 2 (binary)
        Precede the number with a "#".
        Example:    #10010110

    All special symbols (such as "H", "0x", and the hexadecimal numbers
    from A...F) are case-insensitive.  That means capital and small
    letters are equivalent.

MP understands CHARACTERS as:

    -    Individual characters.
        Enclose in single quotes, like 'x'.

    -    Character strings.
        Enclose in double quotes, like "this is a string".

    C special characters (like '\n') are recognized both as individual
    characters and in strings.

    If you type a RETURN in the middle of a string, it is interpreted
    as a space character.  (If you want a real newline character, use
    \n.)  If a string is too long to fit on your screen, break it into
    2 strings (or more), each surrounded by double-quotes.


    All of these numbers/characters are automatically converted into
bytes.  As a result, you cannot specify a number with value greater than
255 (base 10) or less than 0.  If you do, you will get an error message.

    MP also has a "comment" symbol.  This lets you type text that is
ignored by MP.  Any text following a semicolon (";") is ignored until
the end of the line.  (This is just like the Amiga CLI comment symbol.)
(Of course, this does not occur if the semicolon is part of a character
constant or string.)
    Why is a comment symbol useful?  You can put text language commands
in a file and send it to your MIDI instrument.  Comments allow you to
document the meaning of the contents of the file.  For example:

        ; Send a C major chord on MIDI channel 0
        0x90 60 127 64 127 67 127


    EVERY INDIVIDUAL NUMBER/CHARACTER/STRING/COMMENT THAT YOU TYPE
MUST BE SEPARATED FROM ITS NEIGHBORS BY WHITESPACE (blanks, tabs, newlines).
Yes, even comments.  This may change in a later version of the program.


PRACTICING WITH THE TEXT LANGUAGE

    Type the command:

        1>  mp  -it  -ot

This tells MP to translate from text into text, totally bypassing MIDI.
As you type in the text language, you will see your data interpreted by
MP.  To end MP, type control-C (^C).

    When you feel comfortable with the text language, try sending some
data to your synthesizer.  Type:

        1>  mp  -it  -om

Here is some data:

        H90 60 100

This tells the instrument to play Middle C (note 60) at volume (velocity)
100, assuming the instrument is on MIDI channel 0.  To turn off the note:

        H80 60 0

To end MP, type control-C (^C).


USING THE FILE INPUT/OUTPUT OPTIONS TO MAKE NEW WINDOWS

    On the Amiga, you can specify a NEW WINDOW as a file, rather than
an actual disk file.  The syntax is found in your AmigaDOS manual, under
the NewCLI or NewShell command.  For example, to print your output in
a 640x100 window, positioned at screen location (20,25), with window name
"MP-IN", you would use:

        1>  mp ... -g "CON:20/25/640/100/MP-IN" ...

Do similarly for output windows, but use -p instead of -g.


USING REDIRECTION

    You can use the CLI's INPUT REDIRECTION symbol to get input from a
file instead of from the keyboard.  See your AmigaDOS manual for more details.
The syntax is:
            < filename

and it must appear immediately after the command name (MP).  For example:

        1>  mp  < infile  -it -om

to send text data (translated to MIDI) from the file "infile" to the
MIDI instrument.

    Some sample input files are included with this program.

    You may also use the CLI's OUTPUT REDIRECTION symbol to send output
to a file instead of to the screen.  See your AmigaDOS manual for more
details.  The syntax is:

            > filename

and it must appear immediately after the command name (MP).  For example:

        1>  mp  > outfile  -im -ot

to capture MIDI data (translated to text) into the file "outfile".


TRANSLATING BINARY DATA TO/FROM TEXT

    Suppose you have a binary file that you want to translate to
text.  (It does not even have to be a MIDI data file!!)  Just type:

        1>  mp  < binaryFile  -ib -ot

If you prefer to save your text results in a file, type:

        1>  mp  < binaryFile > textFile  -ib -ot


USING AN ALTERNATE MIDI INTERFACE

    By default, the MP assumes that your MIDI interface
is connected to your Amiga's internal serial port.  If this is
not the case, you can override this by using an Amiga environment
variable and the SetEnv command.  (See your Amiga documentation for
full details about SetEnv.)

    The name of the environment variable is MP_MIDI_DEVICE, and its
value must be of the following format:

    1)    The name of the MIDI device driver, located in the
        DEVS: directory of your system disk.  It should be
        something like "midi.device" or "serial2.device".

    2)    One colon character (':').

    3)    The unit number for the device.  If you have only
        1 port using the device, your unit number is probably
        zero.

    Example:    midi.device:2

    Suppose you want to set up MP to use unit 3 the device
"AltMidi.device".  Type:

        1>  SetEnv MP_MIDI_DEVICE AltMidi.device:3

To check that the value was set correctly, type:

        1>  GetEnv MP_MIDI_DEVICE

    If you are using a MIDI interface attached to your internal
serial, port, YOU MAY IGNORE ALL OF THIS STUFF.  By default, MP uses
unit 0 of the device "serial.device".

    I cannot guarantee that MP will work with whatever alternate device
driver you choose.  But I have tested the environment variable mechanism
itself, and it works.


PROBLEMS YOU MAY HAVE WITH MP

    I have tested these programs fairly well on my own equipment:
Amiga 1000, Golden Hawk MIDI Gold interface, and an Oberheim Matrix-12.
If the program doesn't work for you, first check:

(?)    Is the file "serial.device" in the DEVS: directory of your system
    disk?  If not, MP will refuse to run, and you will see an error
    message like one of these:

        Cannot create a message port.
        Cannot create an extended I/O request.
        Cannot open the MIDI device.
        Cannot set the serial parameters.

    Boot your Amiga with an original Workbench disk and try again.

(?)    Are you running a version of the Amiga operating system that is
    older than 1.3?  MP should work with some or all earlier
    versions, but I have not tested this.

(?)    Are your MIDI cables connected properly?  Remember that MIDI OUT
    must always be connected to MIDI IN, and vice-versa.

        SYNTHESIZER            COMPUTER
        -----------            --------
        MIDI IN     <------------------->    MIDI OUT
        MIDI OUT <------------------->    MIDI IN

(?)    Are you using the program correctly?  Double-check the instructions
    above.

(?)    Are you running another program that uses the serial port, such as
    a communications program, printing program, or another MIDI program?
    If so, this other program may be using the serial port.  (MP
    uses the serial port in "shared" mode so it doesn't hog the
    serial port.) Exit your other programs and try again.  If it
    still doesn't work, reboot to make sure that your other programs
    didn't accidently leave the serial port "locked".

    Some programs allow you to "release" their hold on the serial port
    without exiting.  (Example:  Music-X.)  This may be enough to allow
    MP to run.

    If you run MP with the "-im" format (input from MIDI), you cannot
    run MP a second time simultaneously.  This is because the Amiga
    serial port initialization routines will fail if there is another
    program reading the serial port.

(?)    Are you running any other programs simultaneously with MP?
    It is possible that a badly-written program could
    interfere with the operation of other programs.  Boot your Amiga
    with an original Workbench disk and try again.

(?)    Is your synthesizer turned on?  Seriously.  This has happened
    to me.  :-)

If you are doing everything right, then there may be a bug in the
program.  For example, MP should NEVER crash your Amiga.  If you
believe that there is a bug, please contact me (electronic mail is
preferred).  But first, try to reproduce the bug consistently.  Can
you find a particular set of actions, keystrokes, etc., that ALWAYS
make the program crash?  If you can, then I will be able to find the
bug faster.


NOTES ABOUT THE SOURCE CODE

    The file "text.c" contains a good example of using a finite
automaton to read the text language and translate it into bytes.  The
code is fairly robust and easy to modify.  For example, I was able to
add "binary number" support in about 3 minutes, and "string" support in
about 10 minutes.
    The theory of finite automata is extremely important for programmers,
but it can seem very "theoretical" at first.  Believe me, it helps you
write correct programs that are easy to modify later.

    The file "serial.c" contains serial port code that you are welcome
to use.  The function "DoTheIO()" implements asynchronous I/O in a very
multitasking-friendly way.  The function "FastSerialRead()" is patterned
after Commodore's recommended method for reading the serial port quickly.
The method is documented in the AMIGA ROM KERNEL REFERENCE MANUAL:
LIBRARIES AND DEVICES, for version 1.3 of the Amiga Operating System.

    The file "main.c" contains examples of using pointers to functions
and pointers-to-pointers to functions.  (The functions themselves are
defined in "iofunctions.c".)

    The file "getopt.c" contains my version of the powerful and useful
UNIX "getopt()" function.  This gives the programmer a standard interface
for reading command-line options (flags) from the user.  I have used this
file (unchanged) in a dozen programs.

    The "Makefile" is pretty generic.  If you want to add a new
file to the program, just append its name (and its object file's name)
to the SRC and OBJ macros, and type "make".


NOTES ABOUT THE PROGRAM'S INTERNALS (AND LIMITATIONS)

    MP uses a very inefficient method for sending MIDI data and
reading/writing files:  one byte at a time.  This could definitely be
made faster, but takes some cleverness (and some internal buffering).
MP does read MIDI data very efficiently, though.

    This limitation is due to the byte-oriented nature of this program.
Also, when the user is typing text, he/she wants immediate feedback from
a MIDI device.  I'm sure there is a better way to do this than my method.

    I did not build this program for large data transfers.  It is
mainly for transmitting small amounts of data for diagnostic purposes.
This is why I have released the program before its I/O routines are
improved.